Developer Documentation

QuickTime 4 API Documentation

QuickTime 4 Reference

| Previous | Chapter Contents | Chapter Top |

Image Compression Manager Utility Functions

ICMShieldSequenceCursor

Hides the cursor during decompression operations.

pascal OSErr ICMShieldSequenceCursor (ImageSequence seqID);
seqID
Identifies the sequence for which to shield the cursor.

DISCUSSION

Your component may call the ICMShieldSequenceCursor function to manage the display of the cursor during decompression operations.

For correct image display behavior, the cursor must be shielded (hidden) during decompression. By default, the Image Compression Manager handles the cursor for you, hiding it at the beginning of a decompression operation and revealing it at the end.

With the advent of scheduled asynchronous decompression, however, the ICM cannot do as precise a job of managing the cursor, because it does not know exactly when scheduled operations actually begin and end. While the ICM can still manage the cursor, it must hide the cursor when each request is queued, rather than when the request is serviced. This may result in the cursor remaining hidden for long periods of time.

In order to achieve better cursor behavior, you can choose to manage the cursor in your decompressor component. If you so choose, you can use the ICMShieldSequenceCursor function to hide the cursor--the ICM displays the cursor when you call the ICMDecompressComplete function. In this manner, the cursor is hidden only when your component is decompressing and displaying the frame.

Special Considerations

This function may be called at interrupt time.

ICMDecompressComplete

Signals the completion of a decompression operation.

pascal void ICMDecompressComplete (
                     ImageSequence seqID,
                     OSErr err,
                     short flag,
                     ICMCompletionProcRecordPtr completionRtn);
seqID
Identifies the frame's sequence.

err
Indicates whether the operation succeeded or failed. Set this parameter to 0 for successful operations. For failed operations, set the error code appropriate for the failure. For canceled operations (for example, when the ICM calls your component's ImageCodecFlush function), set this parameter to -1.

flag
Completion flags. Note that you may set more than one of these flags to 1. The following flags are defined:

codecCompletionSource
Your component is done with the source buffer. Set this flag to 1 when you are done with the processing associated with the source buffer.

codecCompletionDest
Your component is done with the destination buffer. Set this flag to 1 when you are done with the processing associated with the destination buffer.

codecCompletionDontUnshield
Set this flag to 1 when you do not want the ICM to unshield the cursor as it normally would. Only codecs that are completely managing the cursor themselves should set this flag. See the section "Hardware Cursors" for more information.

completionRtn
Contains a pointer to a completion function structure. That structure identifies the application's completion function, and contains a reference constant associated with the frame. Your component obtains the completion function structure as part of the decompression parameters structure provided by the Image Compression Manager at the start of the decompression operation.

DISCUSSION

Your component must call this function at the end of decompression operations.

Special Considerations

Prior to QuickTime 2.0, decompressor components called the application's completion function directly. For compatibility, that method is still supported except for scheduled asynchronous decompression operations, which must use the ICMDecompressComplete call. Newer decompressors should always use ICMDecompressComplete rather than calling the completion function directly, regardless of the type of decompression operation.

© 1999 Apple Computer, Inc.

| Previous | Chapter Contents | Chapter Top |